Labels feature highlight on hover - #103

Hovering a labels feature now highlights it, the way autoHighlight already highlights a shape. Follow-on to #95, which this depends on.

Deck cannot do this job for labels. A labels tile's picking colour covers the whole quad, so there is no per-label deck object for picking_filterHighlightColor to act on, and enabling autoHighlight would light up the entire tile. The highlight is resolved per fragment instead: the bitmask shader compares the sampled instance id against a highlightedLabelId uniform. A uniform rather than a LUT entry, because the pointer moves constantly and baking hover into the table would re-upload a texture that is megabytes for a large segmentation on every move.

On the vis side the hovered label is runtime render state on a ref plus a version counter (setHoveredLabel), never Render Stack config — it would be meaningless in a saved view, and gating the re-render on crossing into a different label keeps motion within one label free. Points already carry their highlight this way.

Both canvas surfaces, one resolver (5bcda68)

SpatialCanvasViewer (headless/embedded) and SpatialCanvas (full UI) each own a handleHover. The first version wired only the viewer, so the highlight worked in the headless demo and did nothing in the full UI — which is where real datasets are actually opened. Both now call one resolveHoveredLabel in featureTooltipHover.ts; duplication is what caused this, so a single implementation is the fix rather than a tidier copy of it.

The shared resolver reads the label id off the pick object instead of going through getFeaturePickEvent, which also builds a tooltip. The viewer already paid for that call for onFeatureHover; the full UI did not, and adding a second tooltip build per pointer move for a hover tint is not worth it.

The tint prop is deck's own highlightColor (408963c)

Not a bespoke name. Deck blends its highlightColor over a highlighted fragment weighted by that colour's alpha, which is exactly what the labels shader does, and it is RGBA 0-255 on both sides — so the name carries a shared meaning, and one prop covers shapes and labels.

The subtlety worth knowing when reviewing: the labels default must be declared in the layer's defaultProps. props.highlightColor ?? MY_DEFAULT cannot work, because deck's base Layer.defaultProps fills its navy [0, 0, 128, 128] in and the prop is therefore never absent. That is what made an earlier revision draw every hover in deck's navy against a navy fill — looking exactly like the feature was dead. labelsLayer.spec pins the value arriving at the bitmask sublayer, which is the assertion that fails if the default is ever moved back to a use-site fallback.

Verification

Browser-verified, not just compiled:

• test-fixtures/v0.7.2/blobs.zarr on both labels paths, single-scale and multiscale/tiled: the hovered label tints and outlines, the highlight follows the pointer between labels, and clears on moving off.
• A real dataset (1113PMDC1_human_01.zarr, ~16k cell ids) in the full UI, including with the H&E image beneath — which routes through Viv, so picks carry deck's -#view-id# suffix that normalizeDeckLayerId strips.
• With cell_labels and nuclei_labels both enabled — two elements that genuinely share label id 13032 — only the layer under the cursor lights up.

Workspace build, all tests (788), lint:biome, lint:react (only the pre-existing PointsFeatureState warning) and the docs build are green.

Reviewer notes

• Docs updated in the three files Labels filtering and colouring, mirroring shapes #95 touched: layer-prop-flow.mdx (render-path section plus two anti-pattern rows), headless-viewer.mdx, mdv-release-checklist.mdx.
• The useLayerData public-surface tripwire goes 17 -> 18 members for setHoveredLabel; the docblock prose carries the count in words and is updated to match.
• Nothing new reaches a saved Render Stack, so there is no MDV persistence work implied.

🤖 Generated with Claude Code